Pascal Super Library/Pascal Super Library (CW International)(1997).bin/SHELLS/SZ2/README

Text File | 1992-08-31 | 16KB | 452 lines

                       ******************
                       Welcome to SHAZAM!
                       ******************

Documentation for SHAZAM is both "online" and "offline":

[X] ONLINE - The context-sensitive portion is cross-referenced with
    the manual, most of which is also in HyperText format.

[X] OFFLINE - The PRINTDOC program is about to be generated and
    compiled.  It will print the Technical Manual and demonstration
    programs with your choice of formats and margins.  The "Test
    print" option is a 2-page report, so you can make adjustments and
    try different settings.

    All source for units and example programs is included.  You can
    re-use dialogs, hints and help text files as "plug n' play"
    elements of your own programs.


CONTENTS
--------
1 - Getting started
2 - Notes
3 - Installation
4 - Units
5 - Examples
6 - Overview
7 - Acknowledgements
8 - Technical Support



1 - GETTING STARTED
===================
If you are upgrading from version 1.x,  you MUST read UPGRADE.DOC.

To give you an idea of what SHAZAM can do, the following...

    KEYWORDS & ITEMS         HINTS
        |                       |
        V                       V
    ----------------------------------------------
    [ submenu ] file         ;;hint for file stuff
    open   f3                ;;open a file
    save   f2                ;;save window

    [ status ]
    f1 Help                  ;;call HyperText help
    alt-x exit cmQuit        ;;return to DOS
    ----------------------------------------------

...creates a ready-to-run EXE with Help Text & Hints, using overlays
and resources, recovers overlay heap for EXEC, and runs under DOS 2.x
or higher.  By default, SHAZAM allows for use of ExecSWAP, so the
application is unitized (encapsulated) and you get Swap-To-Disk/EMS
capability too, with minimum overhead, less than <6k.

No kidding.

Type the above into a file with an *.DEF extension & press Ctrl-F9.

Don't want overlays?  Use the "/O-" switch, from the DOS prompt or
SETUP|Code dialog.  No ExecSwap?  Use "/X-".  Code, instead of
resources?  Use "/1".  And so on...

Now, for an actual "Exec", you would have to add custom code, BUT
there's a routine in GENERAL.PAS called "VisionExec" (just like
DOS.Exec) which takes care of Turbo Vision housekeeping for you.

There's also pre-done events called "hdLittleDOS", "hdMediumDOS" and
"hdBigDOS" for shelling to the DOS prompt.  Run the ED*.DEF examples
and see the help text for details.

The basic idea of using SHAZAM is:  It codes the "FrameWork" for you,
so you can concentrate on "fleshing out" custom code and Help Text.
This gives you the freedom to experiment with interface design, since
you can re-generate & re-compile anytime with one keystroke (Ctrl-F9).


To accelerate your learning curve
---------------------------------
Start with the ADEMO*.DEF series, in IDE mode.  Type "C:>shazam", use
"File|OPEN" to select a file, then press Ctrl-F9, which will
generate, compile & run a program.


An alternative
--------------
Print the ADEMO*.DEF series, then generate all programs using
command-line mode.  Type "C:>shazam ademo*/m" to generate, compile &
run the whole series at once.


Note on HELP
------------
SHAZAM generated programs will automatically support ALT-F1 (to view
previous help screens) if you patch HELPFILE.PAS with ALTF1.PAT



2 - NOTES
=========
[X] Copyrights

    Please respect any and all copyright notices.

    All parts of this software are copyrighted, including but not
    limited to programs, documentation, source-code and examples.

    As a licensed user, you may use the example programs.  However,
    they may not be sold, given away or otherwise distributed without
    written permission.

    Also, as a licensed user, you are free to incorporate examples
    (definitions, help text, etc.) and source code into your programs.


[X] Documentation

    You should view, or print, all *.DOC files.  Do AINTRO.DOC first,
    before starting on the ADEMO*.DEF series.  You may also want to
    print the ADEMO*.DEF files as you go along.  Since SHAZAM
    automatically loads support files along with definitions, you can
    use "File|Print all" or Ctrl-F4 to print all editor windows
    currently loaded into the Desktop.


[X] Interactive and Command-Line modes

    Both are supported in the same program.  Type "C:\>shazam /?" at
    the command-line for a list of switches, or "C:\shazam" and
    select the SETUP|Code dialog.


[X] PATCHES

    A number of tested patches have been included.  Browse the *.PAT
    files for details.

    APP.PAT - DesqView patch for APP.PAS
    ------------------------------------
    If you want all your Turbo Vision programs to run under DesqView,
    APP.PAT contains a simple modification to accomplish this.  If
    you make this patch, activate the "define" in the "COMPILER.PAS"
    file by adding a dollar sign:

    {DEFINE desqview}   -->  {$DEFINE desqview}

    This is so the "UserScreen" and "CopyScreen" routines in
    GENERAL.PAS will recognize the DesqView patch.


    EDLOAD.PAT - for original EDITORS
    ---------------------------------
    An improved version of EDITORS comes with SHAZAM.  If you want to
    use the original, you must correct this bug in the load/store
    methods, or your program will hang during Desktop load/store.


[X] ONLINE HELP

    SHAZAM comes with its own help file, but if you need Online Help
    for Turbo Vision, don't forget THELP.COM (shipped with Turbo
    Pascal).  It provides memory resident help/reference on both
    Turbo Pascal & Turbo Vision at a relatively low cost in memory
    overhead (about 30k).



3 - INSTALLATION
================
If you need to restore the example code, you can re-run INSTALL.  All
existing files will be over-written.


 Programs
 --------
  INSTALL.EXE - Installation program
  INSTALL.DAT - Installation data

 Archives
 --------
    BABEL - Multiple Language Editor
      DEF - Commonly used Definitions
      DLG - Commonly used Dialogs
 EXAMPLES - Sample definitions and source code
   EXSWAP - Source code for EXECSWAP & EXECPROC
  GENERAL - General purpose code for Turbo Vision
    PATCH - Turbo Vision patches
   SHAZAM - Program, Help and Help Compiler
      TXT - Commonly used Help Text


Instant INSTALL
---------------
Installation was done using "Instant INSTALL", a generic INSTALL
program which supports multiple diskettes using ARC/LZH/ZIP formats
and de-archive programs.  For more information, use the "/?" switch at
the DOS prompt:

    C:\>a:install/?


SHAZAM program installation creates the following directory structure:

    ?:\SHAZAM2\
              \DEF\
              \DLG\
              \TXT\

You are free to re-arrange things to suit you.  Use the SETUP |
Directory dialog to let SHAZAM know where things are.  The most
likely change is to move the program files -- SHAZAM.EXE, SHAZAM.HLP
and SZHC.EXE -- to a directory on your system PATH.


DISK SPACE
----------
Although three megabytes of disk space are needed to install SHAZAM
and run the PRINTDOC program, you can erase the examples and keep
only the program files.

To free up disk space (ie: before a backup), run CLEAN.BAT.  This
erases only generated files, which you can easily re-create.


PORTABLE SHAZAM
---------------
If you must work "on-site" to develop an interface, it is possible to
fit SHAZAM, the compiler (TPC.EXE) and the Turbo Vision units on a
high-density diskette of either size.

The bare essentials are:

    [X] SHAZAM.EXE - main program.  (SHAZAM.HLP is optional)
    [X] SZHC.EXE - new Help Compiler (old TVHC.EXE may be used)

...plus the compiler and TV units, of course.



4 - UNITS
=========
Only the Turbo Vision units are needed to compile a generated
application.  However, a number of utility & workhorse units are
included, as used by SHAZAM itself and many of the examples:


GENERAL.PAS   Standard events, dialog handling, strings, conversion
              and so on.  Routines such as "hdSaveDesktop",
              "hdLoadDesktop", "VisionExec", etc. may be called
              within any Turbo Vision application.


PRINT.PAS     Report & print capability for Turbo Vision or DOS, with
              support for Generic, Dot-Matrix, LaserJet and
              DaisyWheel printers.

              Interruptible dialogs are easy to use, can print to
              disk or LPT ports, and are ready for use with
              EditWindows, printing from disk files, from the
              FileViewer or other PCollections (see PPRINT.INT).

              For user control of printing, the library directories
              contain re-usable dialogs, hints and help text for page
              & printer setup (PAGE.DLG & PRINT.DLG, HINTPRN.DEF,
              PRNSETUP.TXT).


EDITORS.PAS   An enhancement of the original EDITORS, providing the
              following features via direct keystrokes and/or from a
              menu:

              * Centering                         * Right-margin
              * Go to line number                 * TAB stops
              * Place markers (10 per window)     * Word wrap

              Several *.DEF, *.DLG and *.TXT files were created to
              enhance this unit.  Actually, you have everything used
              by this version of SHAZAM.

              See ED*.DEF for examples, EDITORS.DOC for unit details.


EXECSWAP.PAS
&
EXECPROC.PAS  These provide swap-to-disk/EMS for EXEC calls.  Note
              that using "VisionExec" in place of "DOS.Exec" takes
              care of TV house-keeping as well.  See the EXEC*.DOC
              files for details, ADEMO9.DEF for example.


LISTREZ.PAS   Program to list contents of resource files (*.REZ).



5 - EXAMPLES
============
The example definitions will generate as either code or resource
based programs.  For those examples which switch MenuBars/Boxes and
StatusLines, compiler symbols are used in program logic.

If ALL framework/interface elements are either code OR resources (but
not a mix), SHAZAM automatically defines the compiler symbols "code"
or "resource", respectively.  If you use mixed options, be forewarned
that this may affect the program logic in the examples.



6 - OVERVIEW
============
SHAZAM generates complete TApplications, including Help Text and
Hints, so you can test the look & feel of your visual shell.

You can generate, compile and run directly from SHAZAM.  The Help
Compiler and Code Compiler are called as needed.

The Turbo Vision objects provide you with a set of "bones", around
which you add the "meat" of your application.  With SHAZAM, you
change the skeleton to make different animals.  This lets you
concentrate on "fleshing out" your program, rather than writing and
debugging user-interface code.  (OK, OK, enough with the analogies
already...)


                        COMPOSING AN INTERFACE

MenuBars, MenuBoxes, StatusLines and Hints are composed one line at a
time, in a definition (*.DEF) file.  In most cases, you need only two
or three of SHAZAM's keywords.  In addition, you can design dialogs
interactively using the built-in Dialog Editor (Alt-D).

There aren't many limits to what you can do.  As you work through the
examples, bear in mind that SHAZAM was used to design itself; as well
as compile, overlay, execswap, etc.  It's just a tad easier than
hand-coding...and you can re-use what you create in other programs.
Especially since include files can be nested for both definitions and
help text.

The ADEMO*.DEF series shows how to travel the road from interface to
working program.  It might be handy to use the PRINTDOC program
to extract a Table of Contents and/or just the documentation from all
example *.DEF files.


                          MAKE IT A PROGRAM

One use of SHAZAM is to create, revise and experiment with user
interfaces.  But you can maintain software with it, too.

With SHAZAM's "scanning" ability and the [ EXTERNAL ] keyword, you
can easily add methods and events from include files and units.

You can quickly develop and change interfaces, using just code and no
online help.  Or you can maintain fully resourced, overlaid programs
with HyperText Help and Hint Text, using switchable MenuBars/Boxes,
StatusLines and Hint sets.

Foreign translations are also made easier:  See the BABEL example.

One thing to keep in mind:  SHAZAM maintains and regenerates itself,
and it was built from the Turbo Vision and GENERAL units.


                          DESIGN PHILOSOPHY

Although some of the examples use code from the GENERAL, PRINT and
EXEC*.PAS units, code generated by SHAZAM requires only the standard
Turbo Vision units.  No dependencies are introduced, with the
exception of ExecSWAP, and that can be turned off ("/x-" switch).



7 - ACKNOWLEDGEMENTS
====================


EXECSWAP
--------
This source-code is by Turbo Power Software and is included by
permission.  The company has a forum library on CompuServe (PCVENB)
and has other programming products.  They may be contacted by:

Kim Kokkonen                                 Information 719.260.6641
TURBO POWER SOFTWARE                              Orders 800.333.4160
Post Office Box 49009                                Fax [phone]
Colorado Springs, CO 80949-9009                 CompuServe 76004.2611
USA                                INTERNET [e-mail]


DIALOG EDITOR
-------------
The built-in Dialog Editor was derived by permission from L. David
Baldwin's original DLGDSN (Dialogbox Design).  It will read and
export the *.DLG file format.


EDITORS
-------
This unit is adapted from Al Andersen's original NEWEDIT package, by
permission.


BABEL Multi-Language Editor
---------------------------
The translations for the definitions (*.DEF) and help text (*.TXT)
were done by:


Thomas Davidson
PASO del NORTE LENGUAJE                            Voice 915.564.0990
2713 Hamilton Ave                                    Fax [phone]
El Paso, TX 79930-3639                          CompuServe 75540.1022
USA                                INTERNET [e-mail]

Note - Work was done via CompuServe EMAIL.



8 - TECHNICAL SUPPORT
=====================
If you have any problems, you can get the best Technical Support by
Electronic Mail or telephone.  For subjects of a more leisurely
nature, you can send postal mail.

Johnathan J. Stein
STEIN RESEARCH & ENGINEERING                       Voice 419.666.7103
Post Office Box 346                                  Fax [phone]
Perrysburg, OH  43552                            CompuServe 76576.470
USA                                 INTERNET [e-mail]



{///////////////////////////////////////////////////////////////////
//                           THE END                              //
////////////////////////////////////////////////////////////////////
//                                                                //
// First, there was SHAZAM I:  "To TAME TApplication!"            //
//       Then came SHAZAM II:  "The WRATH of RESOURCES!"          //
//- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - //
//                  Next, our Hero returns in:                    //
//- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - //
//                                                                //
//                         SHAZAM III                             //
//                         ----------                             //
//               "The SEARCH for SERENDIPITY!"                    //
//                                                                //
////////////////////////////////////////////////////////////////////
//             Advance tickets sent to Licensed Users             //
///////////////////////////////////////////////////////////////////}